home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Light ROM 3
/
Light ROM 3 - Disc 2.iso
/
programs
/
amiga
/
imagefx
/
imagekit
/
imagekit.lha
/
ImageFX_SDK
/
doc
/
Loader.autodoc
< prev
next >
Wrap
Text File
|
1994-11-22
|
14KB
|
340 lines
TABLE OF CONTENTS
loaders/LM_Load
loaders/LM_LoadPalette
loaders/LM_Signatures
loaders/LM_CheckFile
loaders/LM_Load loaders/LM_Load
NAME
LM_Load -- Load an image from disk.
SYNOPSIS
buffer = LM_Load ( filename, id, args )
D0.L A0 D0.L A1
struct Buffer *LM_Load ( char *filename, int id, LONG *args );
FUNCTION
Attempts to load the given file as the format that this
loader module recognizes, translating it to 24-bit if
necessary. Returns a valid Buffer structure which may
be directly used by ImageFX.
INPUTS
filename - filename of the image to load.
id - ID code, typically used to indicate which
"flavor" of the file format we're trying to
load. This is passed unchanged from Montage
from what was obtained through the
LoadFormat structure ID field by
LM_Signatures(). In most cases, this can
be ignored.
args - Arguments from an Arexx command invocation.
Most loaders will not need to worry about this,
but it can be used to allow passing parameters
to the loader via. Arexx commands. Note that
you must fill in the ModuleBase->CmdTable
parameter for this to be valid. See the
example ANIM loading code for an example of
using this argument.
RESULT
buffer - A valid Buffer structure, with the following
fields filled in:
Name - Filename passed to LM_Load().
Type - Short description of file type.
Flags - Set to 0.
Width - Width of buffer in pixels.
Height - Height of buffer in pixels.
BitsPerPlane- Always 8.
Depth - Depth of buffer; 1 for grey, 3 for
color.
Planes[] - Pointers to either one or three
contiguous blocks of image data.
For a greyscale image this will
be a single plane of 8-bit
greyscale values; for a color image
this will be three planes of 8-bit
Red, Green, and Blue values.
DPIX, DPIY - Dots per inch horizontally and
vertically (if specified).
PixAspectX,
PixAspectY - Pixel aspect ratio X and Y (if
specified).
You should use the function AllocBuffer() to
allocate your Buffer structure, as this does
a lot of necessary initialization from the arguments
passed to it.
A NULL return indicates an error of some kind,
with a more descriptive error code in the
global error variable set with SetError().
EXAMPLE
NOTES
You should make the user aware of the size of the image you
are loading as soon as possible. That is, as soon as you
find out the size of the image by reading the file, you
should call ShowStatus() to display that information to the
user while reading the rest of the file.
Make sure this function gracefully handles disk errors.
You should be aware that future versions of ImageFX may define a new
loader module vector that will take a pointer to an AmigaDOS file
handle instead of a filename. It would not be a bad idea to organize
your code now such that the LM_Load() vector just opens the file and
passes control to a second function. Like this:
LM_LoadHandle (BPTR handle, int id, LONG *args)
{
}
LM_Load (char *name, int id, LONG *args)
{
BPTR handle;
if (handle = Open(name, MODE_OLDFILE)) {
LM_LoadHandle(handle, id, args);
Close(handle);
}
}
BUGS
SEE ALSO
loaders/LM_Signatures,scan/buf.h
loaders/LM_LoadPalette loaders/LM_LoadPalette
NAME
LM_LoadPalette -- Read a color palette from an image file.
SYNOPSIS
success = LM_LoadPalette ( filename, palette, id )
D0.L A0 A1 D0.L
BOOL LM_LoadPalette ( char *filename, struct Palette *palette, int id );
FUNCTION
Attempts to read a palette from the file given into the Palette
structure provided. If this loader's file format does not support
a palette (a 24-bit format only), then an error should be returned.
INPUTS
filename - filename of the file to read a palette from.
palette - where to store the resulting palette read from
the file. The following fields in the Palette
structure should be filled in:
Depth - depth of palette in bitplanes.
Represents the minimum depth required
to store this palette.
Count - number of entries in the palette.
Does not necessarily have to be
1 << Depth, but in most cases it
will be.
Table - pointer to where to store the palette
entries themselves. Each entry consists
of 8-bits each of Red, Green, and
Blue, in that order, so each palette
entry is 3-bytes long in this table.
If the palette is greyscale, then
equal values of red, green, and
blue must be stored.
NumRanges - this indicates the maximum
number of ranges that the caller
can handle in his Palette structure.
Do NOT read more than this number
of ranges into the Palette structure!
LowRange - pointer to array of where to store
the lower palette register of a range.
If the format you are loading does not
support color palette ranges, then you
should leave this alone.
HighRange - pointer to array of where to store
the upper palette register of a range.
If the format you are loading does not
support color palette ranges, then you
should leave this alone.
id - ID code, typically used to indicate which
"flavor" of the file format we're trying to
load. This is passed unchanged from ImageFX
from what was obtained through the
LoadFormat structure ID field by LM_Signatures().
In most cases, this can be ignored.
RESULT
success - boolean success code, TRUE if successful, FALSE
if something went wrong. A further error code
should be set with the SetError() function.
EXAMPLE
NOTES
Make sure this function gracefully handles disk errors.
BUGS
SEE ALSO
scan/loadsave.h
loaders/LM_Signatures loaders/LM_Signatures
NAME
LM_Signatures - Report the "signature" bytes to match for this
file format.
SYNOPSIS
array = LM_Signatures ( );
D0.L
struct LoadFormat *LM_Signatures ( void );
FUNCTION
Reports to ImageFX the bytes that must be present in the
first bit of a file in order for it to be considered as the
format that this loader can handle. Note that more than one
"signature" can be reported as different "flavors" of the file
format... for example, an ILBM loader could report that it can
handle a FORM ILBM or a FORM ANIM.
Returning NULL indicates that you want to do custom file
identification, bypassing the normal (easy) file identification
used by simpler loaders. If you want to do custom file
identification, you must supply the new function LM_CheckFile()
as described below.
INPUTS
None.
RESULT
array - an array of LoadFormat structures, terminated with
a structure with the Identifier field set to NULL.
Each LoadFormat structure should be filled in as
follows by the loader:
Identifier - pointer to a string of bytes that
must be present at the beginning of
the file. An identifier byte that is
the ASCII symbol "?" will match ANY
value in the input file. Thus the
correct identifier string for an ILBM
loader would be "FORM????ILBM". The
identifier string does NOT have to be
null-terminated. Note: if you need
to match an ASCII question mark in
the header, you're screwed.
Length - Number of bytes in the identifier
string.
Name - User-readable name of the format.
This is mainly for the "Load As"
function, to give the user a name
to pick. It can also be used as
a method of selecting a file format
to load via. Arexx. Avoid spaces
in this name.
ID - An ID strictly for the use of the
loader. When a file matches the
identifier string, this ID value is
passed to the loader in the LM_Load()
call. This can be used by the
loader to know which identifier was
matched if it can handle more than one.
Flags - Flag bits for this format. The following
values may be used:
LOA_NOFILE - ImageFX will not present
a file requester to select a
filename when loading this format.
This is used in, for example,
clipboard loaders.
LOA_MULTI - Indicates that this file
format contains multiple images
or frames, ie. an animation.
A NULL return indicates you want to do custom
file identification.
EXAMPLE
static struct LoadFormat loadformats[] =
{
{ "FORM????ILBM", 12, "IFF_Picture", 0, 0 },
{ "FORM????ANIM", 12, "IFF_Animation", 1, 0 },
{ NULL }
};
struct LoadFormat *LM_Signatures (void)
{
return(loadformats);
}
NOTES
BUGS
SEE ALSO
loaders/LM_Load,loaders/LM_CheckFile,scan/loadsave.h
loaders/LM_CheckFile loaders/LM_CheckFile
NAME
LM_CheckFile - Test to see whether a file is in the format
expected by this loader, ie. custom file
identification.
SYNOPSIS
success = LM_CheckFile ( filename );
D0.L A0
BOOL LM_CheckFile ( char *filename );
FUNCTION
Checks the supplied file to see if it in the format recognized
by this loader. Presumeably, checking for this type of file
requires more work than just matching the first few bytes in
the file. You are given only the name of the file that Image
Scan is trying to load, you must open it yourself and read
whatever bytes are necessary to do the checking.
You will need to use this method for any file format that does
not have an explicit "magic" constant at the beginning of the
file, but can still be identified by some pattern of bytes
somewhere within the file (ie. widths, heights, or whatever).
INPUTS
filename - pointer to the name of the file to be checked.
RESULT
success - Return TRUE if you recognize this file format and
can load it. (You can expect a call to your LM_Load()
function soon after returning TRUE.) Otherwise, return
FALSE to allow ImageFX to continue checking the file
with other loader modules.
EXAMPLE
NOTES
BUGS
SEE ALSO
loaders/LM_Signatures,scan/loadsave.h